Amiga Tools 5/Amiga Tools 5.iso/tools/developer-tools/andere sprachen/perl5/man/catp/perlembed.0

Text File | 1996-03-02 | 70.6 KB | 859 lines

PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


NNNNAAAAMMMMEEEE
       perlembed - how to embed perl in your C program

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
       PPPPRRRREEEEAAAAMMMMBBBBLLLLEEEE

       Do you want to:

       UUUUsssseeee CCCC ffffrrrroooommmm PPPPeeeerrrrllll????
            Read the _p_e_r_l_c_a_l_l manpage and the _p_e_r_l_x_s manpage.

       UUUUsssseeee aaaa UUUUNNNNIIIIXXXX pppprrrrooooggggrrrraaaammmm ffffrrrroooommmm PPPPeeeerrrrllll????
            Read about backquotes and the ssssyyyysssstttteeeemmmm entry in the
            _p_e_r_l_f_u_n_c manpage and the eeeexxxxeeeecccc entry in the _p_e_r_l_f_u_n_c
            manpage.

       UUUUsssseeee PPPPeeeerrrrllll ffffrrrroooommmm PPPPeeeerrrrllll????
            Read about the ddddoooo entry in the _p_e_r_l_f_u_n_c manpage and
            the eeeevvvvaaaallll entry in the _p_e_r_l_f_u_n_c manpage and the uuuusssseeee
            entry in the _p_e_r_l_m_o_d manpage and the rrrreeeeqqqquuuuiiiirrrreeee entry in
            the _p_e_r_l_m_o_d manpage.

       UUUUsssseeee CCCC ffffrrrroooommmm CCCC????
            Rethink your design.

       UUUUsssseeee PPPPeeeerrrrllll ffffrrrroooommmm CCCC????
            Read on...

       RRRROOOOAAAADDDDMMMMAAAAPPPP

       the section on _C_o_m_p_i_l_i_n_g _y_o_u_r _C _p_r_o_g_r_a_m

       There's one example in each of the five sections:

       the section on _A_d_d_i_n_g _a _P_e_r_l _i_n_t_e_r_p_r_e_t_e_r _t_o _y_o_u_r _C _p_r_o_g_r_a_m

       the section on _C_a_l_l_i_n_g _a _P_e_r_l _s_u_b_r_o_u_t_i_n_e _f_r_o_m _y_o_u_r _C
       _p_r_o_g_r_a_m

       the section on _E_v_a_l_u_a_t_i_n_g _a _P_e_r_l _s_t_a_t_e_m_e_n_t _f_r_o_m _y_o_u_r _C
       _p_r_o_g_r_a_m

       the section on _P_e_r_f_o_r_m_i_n_g _P_e_r_l _p_a_t_t_e_r_n _m_a_t_c_h_e_s _a_n_d
       _s_u_b_s_t_i_t_u_t_i_o_n_s _f_r_o_m _y_o_u_r _C _p_r_o_g_r_a_m

       the section on _F_i_d_d_l_i_n_g _w_i_t_h _t_h_e _P_e_r_l _s_t_a_c_k _f_r_o_m _y_o_u_r _C
       _p_r_o_g_r_a_m

       This documentation is UNIX specific.

       CCCCoooommmmppppiiiilllliiiinnnngggg yyyyoooouuuurrrr CCCC pppprrrrooooggggrrrraaaammmm

       Every C program that uses Perl must link in the _p_e_r_l
       _l_i_b_r_a_r_y.



30/Jan/96                perl 5.002 with                        1





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


       What's that, you ask?  Perl is itself written in C; the
       perl library is the collection of compiled C programs that
       were used to create your perl executable (_/_u_s_r_/_b_i_n_/_p_e_r_l or
       equivalent).  (Corollary: you can't use Perl from your C
       program unless Perl has been compiled on your machine, or
       installed properly--that's why you shouldn't blithely copy
       Perl executables from machine to machine without also
       copying the _l_i_b directory.)

       Your C program will--usually--allocate, "run", and
       deallocate a _P_e_r_l_I_n_t_e_r_p_r_e_t_e_r object, which is defined in
       the perl library.

       If your copy of Perl is recent enough to contain this
       documentation (5.002 or later), then the perl library (and
       _E_X_T_E_R_N_._h and _p_e_r_l_._h, which you'll also need) will reside
       in a directory resembling this:

           ////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////yyyyoooouuuurrrr____aaaarrrrcccchhhhiiiitttteeeeccccttttuuuurrrreeee____hhhheeeerrrreeee////CCCCOOOORRRREEEE

       or perhaps just

           ////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////CCCCOOOORRRREEEE

       or maybe something like

           ////uuuussssrrrr////oooopppptttt////ppppeeeerrrrllll5555////CCCCOOOORRRREEEE

       Execute this statement for a hint about where to find
       CORE:

           ppppeeeerrrrllll ----eeee ''''uuuusssseeee CCCCoooonnnnffffiiiigggg;;;; pppprrrriiiinnnntttt $$$$CCCCoooonnnnffffiiiigggg{{{{aaaarrrrcccchhhhlllliiiibbbb}}}}''''

       Here's how you might compile the example in the next
       section, the section on _A_d_d_i_n_g _a _P_e_r_l _i_n_t_e_r_p_r_e_t_e_r _t_o _y_o_u_r
       _C _p_r_o_g_r_a_m, on a DEC Alpha running the OSF operating
       system:

           %%%% cccccccc ----oooo iiiinnnntttteeeerrrrpppp iiiinnnntttteeeerrrrpppp....cccc ----LLLL////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////aaaallllpppphhhhaaaa----ddddeeeecccc____oooossssffff////CCCCOOOORRRREEEE
           ----IIII////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////aaaallllpppphhhhaaaa----ddddeeeecccc____oooossssffff////CCCCOOOORRRREEEE ----llllppppeeeerrrrllll ----llllmmmm

       You'll have to choose the appropriate compiler (_c_c, _g_c_c,
       et al.)  and library directory (_/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_._._.)  for
       your machine.  If your compiler complains that certain
       functions are undefined, or that it can't locate _-_l_p_e_r_l,
       then you need to change the path following the -L.  If it
       complains that it can't find _E_X_T_E_R_N_._h or _p_e_r_l_._h, you need
       to change the path following the -I.

       You may have to add extra libraries as well.  Which ones?
       Perhaps those printed by

          ppppeeeerrrrllll ----eeee ''''uuuusssseeee CCCCoooonnnnffffiiiigggg;;;; pppprrrriiiinnnntttt $$$$CCCCoooonnnnffffiiiigggg{{{{lllliiiibbbbssss}}}}''''




30/Jan/96                perl 5.002 with                        2





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


       AAAAddddddddiiiinnnngggg aaaa PPPPeeeerrrrllll iiiinnnntttteeeerrrrpppprrrreeeetttteeeerrrr ttttoooo yyyyoooouuuurrrr CCCC pppprrrrooooggggrrrraaaammmm

       In a sense, perl (the C program) is a good example of
       embedding Perl (the language), so I'll demonstrate
       embedding with _m_i_n_i_p_e_r_l_m_a_i_n_._c, from the source
       distribution.  Here's a bastardized, non-portable version
       of _m_i_n_i_p_e_r_l_m_a_i_n_._c containing the essentials of embedding:

           ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
           ####iiiinnnncccclllluuuuddddeeee <<<<EEEEXXXXTTTTEEEERRRRNNNN....hhhh>>>>               ////**** ffffrrrroooommmm tttthhhheeee PPPPeeeerrrrllll ddddiiiissssttttrrrriiiibbbbuuuuttttiiiioooonnnn     ****////
           ####iiiinnnncccclllluuuuddddeeee <<<<ppppeeeerrrrllll....hhhh>>>>                 ////**** ffffrrrroooommmm tttthhhheeee PPPPeeeerrrrllll ddddiiiissssttttrrrriiiibbbbuuuuttttiiiioooonnnn     ****////

           ssssttttaaaattttiiiicccc PPPPeeeerrrrllllIIIInnnntttteeeerrrrpppprrrreeeetttteeeerrrr ****mmmmyyyy____ppppeeeerrrrllll;;;;  ////************    TTTThhhheeee PPPPeeeerrrrllll iiiinnnntttteeeerrrrpppprrrreeeetttteeeerrrr    ************////

           iiiinnnntttt mmmmaaaaiiiinnnn((((iiiinnnntttt aaaarrrrggggcccc,,,, cccchhhhaaaarrrr ********aaaarrrrggggvvvv,,,, cccchhhhaaaarrrr ********eeeennnnvvvv))))
           {{{{
               mmmmyyyy____ppppeeeerrrrllll ==== ppppeeeerrrrllll____aaaalllllllloooocccc(((())));;;;
               ppppeeeerrrrllll____ccccoooonnnnssssttttrrrruuuucccctttt((((mmmmyyyy____ppppeeeerrrrllll))));;;;
               ppppeeeerrrrllll____ppppaaaarrrrsssseeee((((mmmmyyyy____ppppeeeerrrrllll,,,, NNNNUUUULLLLLLLL,,,, aaaarrrrggggcccc,,,, aaaarrrrggggvvvv,,,, eeeennnnvvvv))));;;;
               ppppeeeerrrrllll____rrrruuuunnnn((((mmmmyyyy____ppppeeeerrrrllll))));;;;
               ppppeeeerrrrllll____ddddeeeessssttttrrrruuuucccctttt((((mmmmyyyy____ppppeeeerrrrllll))));;;;
               ppppeeeerrrrllll____ffffrrrreeeeeeee((((mmmmyyyy____ppppeeeerrrrllll))));;;;
           }}}}

       Now compile this program (I'll call it _i_n_t_e_r_p_._c) into an
       executable:

           %%%% cccccccc ----oooo iiiinnnntttteeeerrrrpppp iiiinnnntttteeeerrrrpppp....cccc ----LLLL////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////aaaallllpppphhhhaaaa----ddddeeeecccc____oooossssffff////CCCCOOOORRRREEEE
           ----IIII////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////aaaallllpppphhhhaaaa----ddddeeeecccc____oooossssffff////CCCCOOOORRRREEEE ----llllppppeeeerrrrllll ----llllmmmm

       After a successful compilation, you'll be able to use
       _i_n_t_e_r_p just like perl itself:

           %%%% iiiinnnntttteeeerrrrpppp
           pppprrrriiiinnnntttt """"PPPPrrrreeeettttttttyyyy GGGGoooooooodddd PPPPeeeerrrrllll \\\\nnnn"""";;;;
           pppprrrriiiinnnntttt """"11110000888899990000 ---- 9999888800001111 iiiissss """",,,, 11110000888899990000 ---- 9999888800001111;;;;
           <<<<CCCCTTTTRRRRLLLL----DDDD>>>>
           PPPPrrrreeeettttttttyyyy GGGGoooooooodddd PPPPeeeerrrrllll
           11110000888899990000 ---- 9999888800001111 iiiissss 1111000088889999

       or

           %%%% iiiinnnntttteeeerrrrpppp ----eeee ''''pppprrrriiiinnnnttttffff((((""""%%%%xxxx"""",,,, 3333777733335555999922228888555555559999))))''''
           ddddeeeeaaaaddddbbbbeeeeeeeeffff

       You can also read and execute Perl statements from a file
       while in the midst of your C program, by placing the
       filename in _a_r_g_v_[_1_] before calling _p_e_r_l___r_u_n_(_).

       CCCCaaaalllllllliiiinnnngggg aaaa PPPPeeeerrrrllll ssssuuuubbbbrrrroooouuuuttttiiiinnnneeee ffffrrrroooommmm yyyyoooouuuurrrr CCCC pppprrrrooooggggrrrraaaammmm

       To call individual Perl subroutines, you'll need to remove
       the call to _p_e_r_l___r_u_n_(_) and replace it with a call to
       _p_e_r_l___c_a_l_l___a_r_g_v_(_).



30/Jan/96                perl 5.002 with                        3





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


       That's shown below, in a program I'll call _s_h_o_w_t_i_m_e_._c.

           ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
           ####iiiinnnncccclllluuuuddddeeee <<<<EEEEXXXXTTTTEEEERRRRNNNN....hhhh>>>>
           ####iiiinnnncccclllluuuuddddeeee <<<<ppppeeeerrrrllll....hhhh>>>>

           ssssttttaaaattttiiiicccc PPPPeeeerrrrllllIIIInnnntttteeeerrrrpppprrrreeeetttteeeerrrr ****mmmmyyyy____ppppeeeerrrrllll;;;;

           iiiinnnntttt mmmmaaaaiiiinnnn((((iiiinnnntttt aaaarrrrggggcccc,,,, cccchhhhaaaarrrr ********aaaarrrrggggvvvv,,,, cccchhhhaaaarrrr ********eeeennnnvvvv))))
           {{{{
               mmmmyyyy____ppppeeeerrrrllll ==== ppppeeeerrrrllll____aaaalllllllloooocccc(((())));;;;
               ppppeeeerrrrllll____ccccoooonnnnssssttttrrrruuuucccctttt((((mmmmyyyy____ppppeeeerrrrllll))));;;;

               ppppeeeerrrrllll____ppppaaaarrrrsssseeee((((mmmmyyyy____ppppeeeerrrrllll,,,, NNNNUUUULLLLLLLL,,,, aaaarrrrggggcccc,,,, aaaarrrrggggvvvv,,,, eeeennnnvvvv))));;;;

                                            ////************ TTTThhhhiiiissss rrrreeeeppppllllaaaacccceeeessss ppppeeeerrrrllll____rrrruuuunnnn(((()))) ************////
               ppppeeeerrrrllll____ccccaaaallllllll____aaaarrrrggggvvvv((((""""sssshhhhoooowwwwttttiiiimmmmeeee"""",,,, GGGG____DDDDIIIISSSSCCCCAAAARRRRDDDD |||| GGGG____NNNNOOOOAAAARRRRGGGGSSSS,,,, aaaarrrrggggvvvv))));;;;
               ppppeeeerrrrllll____ddddeeeessssttttrrrruuuucccctttt((((mmmmyyyy____ppppeeeerrrrllll))));;;;
               ppppeeeerrrrllll____ffffrrrreeeeeeee((((mmmmyyyy____ppppeeeerrrrllll))));;;;
           }}}}

       where _s_h_o_w_t_i_m_e is a Perl subroutine that takes no
       arguments (that's the _G___N_O_A_R_G_S) and for which I'll ignore
       the return value (that's the _G___D_I_S_C_A_R_D).  Those flags, and
       others, are discussed in the _p_e_r_l_c_a_l_l manpage.

       I'll define the _s_h_o_w_t_i_m_e subroutine in a file called
       _s_h_o_w_t_i_m_e_._p_l:

           pppprrrriiiinnnntttt """"IIII sssshhhhaaaannnn''''tttt bbbbeeee pppprrrriiiinnnntttteeeedddd...."""";;;;

           ssssuuuubbbb sssshhhhoooowwwwttttiiiimmmmeeee {{{{
               pppprrrriiiinnnntttt ttttiiiimmmmeeee;;;;
           }}}}

       Simple enough.  Now compile and run:

           %%%% cccccccc ----oooo sssshhhhoooowwwwttttiiiimmmmeeee sssshhhhoooowwwwttttiiiimmmmeeee....cccc ----LLLL////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////aaaallllpppphhhhaaaa----ddddeeeecccc____oooossssffff////CCCCOOOORRRREEEE
           ----IIII////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////aaaallllpppphhhhaaaa----ddddeeeecccc____oooossssffff////CCCCOOOORRRREEEE ----llllppppeeeerrrrllll ----llllmmmm

           %%%% sssshhhhoooowwwwttttiiiimmmmeeee sssshhhhoooowwwwttttiiiimmmmeeee....ppppllll
           888811118888222288884444555599990000

       yielding the number of seconds that elapsed between
       January 1, 1970 (the beginning of the UNIX epoch), and the
       moment I began writing this sentence.

       If you want to pass some arguments to the Perl subroutine,
       or you want to access the return value, you'll need to
       manipulate the Perl stack, demonstrated in the last
       section of this document: the section on _F_i_d_d_l_i_n_g _w_i_t_h _t_h_e
       _P_e_r_l _s_t_a_c_k _f_r_o_m _y_o_u_r _C _p_r_o_g_r_a_m





30/Jan/96                perl 5.002 with                        4





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


       EEEEvvvvaaaalllluuuuaaaattttiiiinnnngggg aaaa PPPPeeeerrrrllll ssssttttaaaatttteeeemmmmeeeennnntttt ffffrrrroooommmm yyyyoooouuuurrrr CCCC pppprrrrooooggggrrrraaaammmm

       NOTE: This section, and the next, employ some very brittle
       techniques for evaluting strings of Perl code.  Perl 5.002
       contains some nifty features that enable A Better Way
       (such as with the ppppeeeerrrrllll____eeeevvvvaaaallll____ssssvvvv entry in the _p_e_r_l_g_u_t_s
       manpage).  Look for updates to this document soon.

       One way to evaluate a Perl string is to define a function
       (we'll call ours _p_e_r_l___e_v_a_l_(_)) that wraps around Perl's the
       eeeevvvvaaaallll entry in the _p_e_r_l_f_u_n_c manpage.

       Arguably, this is the only routine you'll ever need to
       execute snippets of Perl code from within your C program.
       Your string can be as long as you wish; it can contain
       multiple statements; it can use the rrrreeeeqqqquuuuiiiirrrreeee entry in the
       _p_e_r_l_m_o_d manpage or the ddddoooo entry in the _p_e_r_l_f_u_n_c manpage to
       include external Perl files.

       Our _p_e_r_l___e_v_a_l_(_) lets us evaluate individual Perl strings,
       and then extract variables for coercion into C types.  The
       following program, _s_t_r_i_n_g_._c, executes three Perl strings,
       extracting an iiiinnnntttt from the first, a ffffllllooooaaaatttt from the second,
       and a cccchhhhaaaarrrr **** from the third.

































30/Jan/96                perl 5.002 with                        5





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


          ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
          ####iiiinnnncccclllluuuuddddeeee <<<<EEEEXXXXTTTTEEEERRRRNNNN....hhhh>>>>
          ####iiiinnnncccclllluuuuddddeeee <<<<ppppeeeerrrrllll....hhhh>>>>

          ssssttttaaaattttiiiicccc PPPPeeeerrrrllllIIIInnnntttteeeerrrrpppprrrreeeetttteeeerrrr ****mmmmyyyy____ppppeeeerrrrllll;;;;

          iiiinnnntttt ppppeeeerrrrllll____eeeevvvvaaaallll((((cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg))))
          {{{{
            cccchhhhaaaarrrr ****aaaarrrrggggvvvv[[[[2222]]]];;;;
            aaaarrrrggggvvvv[[[[0000]]]] ==== ssssttttrrrriiiinnnngggg;;;;
            aaaarrrrggggvvvv[[[[1111]]]] ==== NNNNUUUULLLLLLLL;;;;
            ppppeeeerrrrllll____ccccaaaallllllll____aaaarrrrggggvvvv((((""""____eeeevvvvaaaallll____"""",,,, 0000,,,, aaaarrrrggggvvvv))));;;;
          }}}}

          mmmmaaaaiiiinnnn ((((iiiinnnntttt aaaarrrrggggcccc,,,, cccchhhhaaaarrrr ********aaaarrrrggggvvvv,,,, cccchhhhaaaarrrr ********eeeennnnvvvv))))
          {{{{
            cccchhhhaaaarrrr ****eeeemmmmbbbbeeeeddddddddiiiinnnngggg[[[[]]]] ==== {{{{ """""""",,,, """"----eeee"""",,,, """"ssssuuuubbbb ____eeeevvvvaaaallll____ {{{{ eeeevvvvaaaallll $$$$____[[[[0000]]]] }}}}"""" }}}};;;;
            SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnnggggtttthhhh;;;;

            mmmmyyyy____ppppeeeerrrrllll ==== ppppeeeerrrrllll____aaaalllllllloooocccc(((())));;;;
            ppppeeeerrrrllll____ccccoooonnnnssssttttrrrruuuucccctttt(((( mmmmyyyy____ppppeeeerrrrllll ))));;;;

            ppppeeeerrrrllll____ppppaaaarrrrsssseeee((((mmmmyyyy____ppppeeeerrrrllll,,,, NNNNUUUULLLLLLLL,,,, 3333,,,, eeeemmmmbbbbeeeeddddddddiiiinnnngggg,,,, eeeennnnvvvv))));;;;

                                              ////******** TTTTrrrreeeeaaaatttt $$$$aaaa aaaassss aaaannnn iiiinnnntttteeeeggggeeeerrrr ********////
            ppppeeeerrrrllll____eeeevvvvaaaallll((((""""$$$$aaaa ==== 3333;;;; $$$$aaaa ********==== 2222""""))));;;;
            pppprrrriiiinnnnttttffff((((""""aaaa ==== %%%%dddd\\\\nnnn"""",,,, SSSSvvvvIIIIVVVV((((ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""aaaa"""",,,, FFFFAAAALLLLSSSSEEEE))))))))))));;;;

                                              ////******** TTTTrrrreeeeaaaatttt $$$$aaaa aaaassss aaaa ffffllllooooaaaatttt ********////
            ppppeeeerrrrllll____eeeevvvvaaaallll((((""""$$$$aaaa ==== 3333....11114444;;;; $$$$aaaa ********==== 2222""""))));;;;
            pppprrrriiiinnnnttttffff((((""""aaaa ==== %%%%ffff\\\\nnnn"""",,,, SSSSvvvvNNNNVVVV((((ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""aaaa"""",,,, FFFFAAAALLLLSSSSEEEE))))))))))));;;;

                                              ////******** TTTTrrrreeeeaaaatttt $$$$aaaa aaaassss aaaa ssssttttrrrriiiinnnngggg ********////
            ppppeeeerrrrllll____eeeevvvvaaaallll((((""""$$$$aaaa ==== ''''rrrreeeekkkkccccaaaaHHHH llllrrrreeeePPPP rrrreeeehhhhttttoooonnnnAAAA ttttssssuuuuJJJJ'''';;;; $$$$aaaa ==== rrrreeeevvvveeeerrrrsssseeee(((($$$$aaaa))));;;; """"))));;;;
            pppprrrriiiinnnnttttffff((((""""aaaa ==== %%%%ssss\\\\nnnn"""",,,, SSSSvvvvPPPPVVVV((((ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""aaaa"""",,,, FFFFAAAALLLLSSSSEEEE)))),,,, lllleeeennnnggggtttthhhh))))))));;;;

            ppppeeeerrrrllll____ddddeeeessssttttrrrruuuucccctttt((((mmmmyyyy____ppppeeeerrrrllll))));;;;
            ppppeeeerrrrllll____ffffrrrreeeeeeee((((mmmmyyyy____ppppeeeerrrrllll))));;;;
          }}}}

       All of those strange functions with _s_v in their names help
       convert Perl scalars to C types.  They're described in the
       _p_e_r_l_g_u_t_s manpage.

       If you compile and run _s_t_r_i_n_g_._c, you'll see the results of
       using _S_v_I_V_(_) to create an iiiinnnntttt, _S_v_N_V_(_) to create a ffffllllooooaaaatttt,
       and _S_v_P_V_(_) to create a string:

          aaaa ==== 9999
          aaaa ==== 9999....888855559999666600000000
          aaaa ==== JJJJuuuusssstttt AAAAnnnnooootttthhhheeeerrrr PPPPeeeerrrrllll HHHHaaaacccckkkkeeeerrrr






30/Jan/96                perl 5.002 with                        6





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


       PPPPeeeerrrrffffoooorrrrmmmmiiiinnnngggg PPPPeeeerrrrllll ppppaaaatttttttteeeerrrrnnnn mmmmaaaattttcccchhhheeeessss aaaannnndddd ssssuuuubbbbssssttttiiiittttuuuuttttiiiioooonnnnssss ffffrrrroooommmm
       yyyyoooouuuurrrr CCCC pppprrrrooooggggrrrraaaammmm

       Our _p_e_r_l___e_v_a_l_(_) lets us evaluate strings of Perl code, so
       we can define some functions that use it to "specialize"
       in matches and substitutions: _m_a_t_c_h_(_), _s_u_b_s_t_i_t_u_t_e_(_), and
       _m_a_t_c_h_e_s_(_).

          cccchhhhaaaarrrr mmmmaaaattttcccchhhh((((cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg,,,, cccchhhhaaaarrrr ****ppppaaaatttttttteeeerrrrnnnn))));;;;

       Given a string and a pattern (e.g. "m/clasp/" or
       "/\b\w*\b/", which in your program might be represented as
       """"////\\\\\\\\bbbb\\\\\\\\wwww****\\\\\\\\bbbb////""""), returns 1 if the string matches the
       pattern and 0 otherwise.

          iiiinnnntttt ssssuuuubbbbssssttttiiiittttuuuutttteeee((((cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg[[[[]]]],,,, cccchhhhaaaarrrr ****ppppaaaatttttttteeeerrrrnnnn))));;;;

       Given a pointer to a string and an "=~" operation (e.g.
       "s/bob/robert/g" or "tr[A-Z][a-z]"), modifies the string
       according to the operation, returning the number of
       substitutions made.

          iiiinnnntttt mmmmaaaattttcccchhhheeeessss((((cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg,,,, cccchhhhaaaarrrr ****ppppaaaatttttttteeeerrrrnnnn,,,, cccchhhhaaaarrrr ********mmmmaaaattttcccchhhheeeessss[[[[]]]]))));;;;

       Given a string, a pattern, and a pointer to an empty array
       of strings, evaluates $$$$ssssttttrrrriiiinnnngggg ====~~~~ $$$$ppppaaaatttttttteeeerrrrnnnn in an array
       context, and fills in _m_a_t_c_h_e_s with the array elements
       (allocating memory as it does so), returning the number of
       matches found.

       Here's a sample program, _m_a_t_c_h_._c, that uses all three:


























30/Jan/96                perl 5.002 with                        7





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


          ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
          ####iiiinnnncccclllluuuuddddeeee <<<<EEEEXXXXTTTTEEEERRRRNNNN....hhhh>>>>
          ####iiiinnnncccclllluuuuddddeeee <<<<ppppeeeerrrrllll....hhhh>>>>

          ssssttttaaaattttiiiicccc PPPPeeeerrrrllllIIIInnnntttteeeerrrrpppprrrreeeetttteeeerrrr ****mmmmyyyy____ppppeeeerrrrllll;;;;

          iiiinnnntttt eeeevvvvaaaallll((((cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg))))
          {{{{
            cccchhhhaaaarrrr ****aaaarrrrggggvvvv[[[[2222]]]];;;;
            aaaarrrrggggvvvv[[[[0000]]]] ==== ssssttttrrrriiiinnnngggg;;;;
            aaaarrrrggggvvvv[[[[1111]]]] ==== NNNNUUUULLLLLLLL;;;;
            ppppeeeerrrrllll____ccccaaaallllllll____aaaarrrrggggvvvv((((""""____eeeevvvvaaaallll____"""",,,, 0000,,,, aaaarrrrggggvvvv))));;;;
          }}}}

          ////******** mmmmaaaattttcccchhhh((((ssssttttrrrriiiinnnngggg,,,, ppppaaaatttttttteeeerrrrnnnn))))
           ********
           ******** UUUUsssseeeedddd ffffoooorrrr mmmmaaaattttcccchhhheeeessss iiiinnnn aaaa ssssccccaaaallllaaaarrrr ccccoooonnnntttteeeexxxxtttt....
           ********
           ******** RRRReeeettttuuuurrrrnnnnssss 1111 iiiiffff tttthhhheeee mmmmaaaattttcccchhhh wwwwaaaassss ssssuuuucccccccceeeessssssssffffuuuullll;;;; 0000 ooootttthhhheeeerrrrwwwwiiiisssseeee....
           ********////
          cccchhhhaaaarrrr mmmmaaaattttcccchhhh((((cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg,,,, cccchhhhaaaarrrr ****ppppaaaatttttttteeeerrrrnnnn))))
          {{{{
            cccchhhhaaaarrrr ****ccccoooommmmmmmmaaaannnndddd;;;;
            ccccoooommmmmmmmaaaannnndddd ==== mmmmaaaalllllllloooocccc((((ssssiiiizzzzeeeeooooffff((((cccchhhhaaaarrrr)))) **** ssssttttrrrrlllleeeennnn((((ssssttttrrrriiiinnnngggg)))) ++++ ssssttttrrrrlllleeeennnn((((ppppaaaatttttttteeeerrrrnnnn)))) ++++ 33337777))));;;;
            sssspppprrrriiiinnnnttttffff((((ccccoooommmmmmmmaaaannnndddd,,,, """"$$$$ssssttttrrrriiiinnnngggg ==== ''''%%%%ssss'''';;;; $$$$rrrreeeettttuuuurrrrnnnn ==== $$$$ssssttttrrrriiiinnnngggg ====~~~~ %%%%ssss"""",,,,
               ssssttttrrrriiiinnnngggg,,,, ppppaaaatttttttteeeerrrrnnnn))));;;;
            ppppeeeerrrrllll____eeeevvvvaaaallll((((ccccoooommmmmmmmaaaannnndddd))));;;;
            ffffrrrreeeeeeee((((ccccoooommmmmmmmaaaannnndddd))));;;;
            rrrreeeettttuuuurrrrnnnn SSSSvvvvIIIIVVVV((((ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""rrrreeeettttuuuurrrrnnnn"""",,,, FFFFAAAALLLLSSSSEEEE))))))));;;;
          }}}}

          ////******** ssssuuuubbbbssssttttiiiittttuuuutttteeee((((ssssttttrrrriiiinnnngggg,,,, ppppaaaatttttttteeeerrrrnnnn))))
           ********
           ******** UUUUsssseeeedddd ffffoooorrrr ====~~~~ ooooppppeeeerrrraaaattttiiiioooonnnnssss tttthhhhaaaatttt mmmmooooddddiiiiffffyyyy tttthhhheeeeiiiirrrr lllleeeefffftttt----hhhhaaaannnndddd ssssiiiiddddeeee ((((ssss//////////// aaaannnndddd ttttrrrr////////////))))
           ********
           ******** RRRReeeettttuuuurrrrnnnnssss tttthhhheeee nnnnuuuummmmbbbbeeeerrrr ooooffff ssssuuuucccccccceeeessssssssffffuuuullll mmmmaaaattttcccchhhheeeessss,,,, aaaannnndddd
           ******** mmmmooooddddiiiiffffiiiieeeessss tttthhhheeee iiiinnnnppppuuuutttt ssssttttrrrriiiinnnngggg iiiiffff tttthhhheeeerrrreeee wwwweeeerrrreeee aaaannnnyyyy....
           ********////
          iiiinnnntttt ssssuuuubbbbssssttttiiiittttuuuutttteeee((((cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg[[[[]]]],,,, cccchhhhaaaarrrr ****ppppaaaatttttttteeeerrrrnnnn))))
          {{{{
            cccchhhhaaaarrrr ****ccccoooommmmmmmmaaaannnndddd;;;;
            SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnnggggtttthhhh;;;;
            ccccoooommmmmmmmaaaannnndddd ==== mmmmaaaalllllllloooocccc((((ssssiiiizzzzeeeeooooffff((((cccchhhhaaaarrrr)))) **** ssssttttrrrrlllleeeennnn((((****ssssttttrrrriiiinnnngggg)))) ++++ ssssttttrrrrlllleeeennnn((((ppppaaaatttttttteeeerrrrnnnn)))) ++++ 33335555))));;;;
            sssspppprrrriiiinnnnttttffff((((ccccoooommmmmmmmaaaannnndddd,,,, """"$$$$ssssttttrrrriiiinnnngggg ==== ''''%%%%ssss'''';;;; $$$$rrrreeeetttt ==== (((($$$$ssssttttrrrriiiinnnngggg ====~~~~ %%%%ssss))))"""",,,,
               ****ssssttttrrrriiiinnnngggg,,,, ppppaaaatttttttteeeerrrrnnnn))));;;;
            ppppeeeerrrrllll____eeeevvvvaaaallll((((ccccoooommmmmmmmaaaannnndddd))));;;;
            ffffrrrreeeeeeee((((ccccoooommmmmmmmaaaannnndddd))));;;;
            ****ssssttttrrrriiiinnnngggg ==== SSSSvvvvPPPPVVVV((((ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""ssssttttrrrriiiinnnngggg"""",,,, FFFFAAAALLLLSSSSEEEE)))),,,, lllleeeennnnggggtttthhhh))));;;;
            rrrreeeettttuuuurrrrnnnn SSSSvvvvIIIIVVVV((((ppppeeeerrrrllll____ggggeeeetttt____ssssvvvv((((""""rrrreeeetttt"""",,,, FFFFAAAALLLLSSSSEEEE))))))));;;;
          }}}}

          ////******** mmmmaaaattttcccchhhheeeessss((((ssssttttrrrriiiinnnngggg,,,, ppppaaaatttttttteeeerrrrnnnn,,,, mmmmaaaattttcccchhhheeeessss))))
           ********
           ******** UUUUsssseeeedddd ffffoooorrrr mmmmaaaattttcccchhhheeeessss iiiinnnn aaaannnn aaaarrrrrrrraaaayyyy ccccoooonnnntttteeeexxxxtttt....



30/Jan/96                perl 5.002 with                        8





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


           ********
           ******** RRRReeeettttuuuurrrrnnnnssss tttthhhheeee nnnnuuuummmmbbbbeeeerrrr ooooffff mmmmaaaattttcccchhhheeeessss,,,,
           ******** aaaannnndddd ffffiiiillllllllssss iiiinnnn ********mmmmaaaattttcccchhhheeeessss wwwwiiiitttthhhh tttthhhheeee mmmmaaaattttcccchhhhiiiinnnngggg ssssuuuubbbbssssttttrrrriiiinnnnggggssss ((((aaaallllllllooooccccaaaatttteeeessss mmmmeeeemmmmoooorrrryyyy!!!!))))
           ********////
          iiiinnnntttt mmmmaaaattttcccchhhheeeessss((((cccchhhhaaaarrrr ****ssssttttrrrriiiinnnngggg,,,, cccchhhhaaaarrrr ****ppppaaaatttttttteeeerrrrnnnn,,,, cccchhhhaaaarrrr ********mmmmaaaattttcccchhhheeeessss[[[[]]]]))))
          {{{{
            cccchhhhaaaarrrr ****ccccoooommmmmmmmaaaannnndddd;;;;
            SSSSVVVV ****ccccuuuurrrrrrrreeeennnntttt____mmmmaaaattttcccchhhh;;;;
            AAAAVVVV ****aaaarrrrrrrraaaayyyy;;;;
            IIII33332222 nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss;;;;
            SSSSTTTTRRRRLLLLEEEENNNN lllleeeennnnggggtttthhhh;;;;
            iiiinnnntttt iiii;;;;

            ccccoooommmmmmmmaaaannnndddd ==== mmmmaaaalllllllloooocccc((((ssssiiiizzzzeeeeooooffff((((cccchhhhaaaarrrr)))) **** ssssttttrrrrlllleeeennnn((((ssssttttrrrriiiinnnngggg)))) ++++ ssssttttrrrrlllleeeennnn((((ppppaaaatttttttteeeerrrrnnnn)))) ++++ 33338888))));;;;
            sssspppprrrriiiinnnnttttffff((((ccccoooommmmmmmmaaaannnndddd,,,, """"$$$$ssssttttrrrriiiinnnngggg ==== ''''%%%%ssss'''';;;; @@@@aaaarrrrrrrraaaayyyy ==== (((($$$$ssssttttrrrriiiinnnngggg ====~~~~ %%%%ssss))))"""",,,,
               ssssttttrrrriiiinnnngggg,,,, ppppaaaatttttttteeeerrrrnnnn))));;;;
            ppppeeeerrrrllll____eeeevvvvaaaallll((((ccccoooommmmmmmmaaaannnndddd))));;;;
            ffffrrrreeeeeeee((((ccccoooommmmmmmmaaaannnndddd))));;;;
            aaaarrrrrrrraaaayyyy ==== ppppeeeerrrrllll____ggggeeeetttt____aaaavvvv((((""""aaaarrrrrrrraaaayyyy"""",,,, FFFFAAAALLLLSSSSEEEE))));;;;
            nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss ==== aaaavvvv____lllleeeennnn((((aaaarrrrrrrraaaayyyy)))) ++++ 1111;;;; ////******** aaaassssssssuuuummmmeeee $$$$[[[[ iiiissss 0000 ********////
            ****mmmmaaaattttcccchhhheeeessss ==== ((((cccchhhhaaaarrrr ********)))) mmmmaaaalllllllloooocccc((((ssssiiiizzzzeeeeooooffff((((cccchhhhaaaarrrr ****)))) **** nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss))));;;;
            ffffoooorrrr ((((iiii ==== 0000;;;; iiii <<<<==== nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss;;;; iiii++++++++)))) {{{{
              ccccuuuurrrrrrrreeeennnntttt____mmmmaaaattttcccchhhh ==== aaaavvvv____sssshhhhiiiifffftttt((((aaaarrrrrrrraaaayyyy))));;;;
              ((((****mmmmaaaattttcccchhhheeeessss))))[[[[iiii]]]] ==== SSSSvvvvPPPPVVVV((((ccccuuuurrrrrrrreeeennnntttt____mmmmaaaattttcccchhhh,,,, lllleeeennnnggggtttthhhh))));;;;
            }}}}
            rrrreeeettttuuuurrrrnnnn nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss;;;;
          }}}}

          mmmmaaaaiiiinnnn ((((iiiinnnntttt aaaarrrrggggcccc,,,, cccchhhhaaaarrrr ********aaaarrrrggggvvvv,,,, cccchhhhaaaarrrr ********eeeennnnvvvv))))
          {{{{
            cccchhhhaaaarrrr ****eeeemmmmbbbbeeeeddddddddiiiinnnngggg[[[[]]]] ==== {{{{ """""""",,,, """"----eeee"""",,,, """"ssssuuuubbbb ____eeeevvvvaaaallll____ {{{{ eeeevvvvaaaallll $$$$____[[[[0000]]]] }}}}"""" }}}};;;;
            cccchhhhaaaarrrr ****tttteeeexxxxtttt,,,, ********mmmmaaaattttcccchhhheeeessss;;;;
            iiiinnnntttt nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss,,,, iiii;;;;
            iiiinnnntttt jjjj;;;;

            mmmmyyyy____ppppeeeerrrrllll ==== ppppeeeerrrrllll____aaaalllllllloooocccc(((())));;;;
            ppppeeeerrrrllll____ccccoooonnnnssssttttrrrruuuucccctttt(((( mmmmyyyy____ppppeeeerrrrllll ))));;;;

            ppppeeeerrrrllll____ppppaaaarrrrsssseeee((((mmmmyyyy____ppppeeeerrrrllll,,,, NNNNUUUULLLLLLLL,,,, 3333,,,, eeeemmmmbbbbeeeeddddddddiiiinnnngggg,,,, eeeennnnvvvv))));;;;

            tttteeeexxxxtttt ==== ((((cccchhhhaaaarrrr ****)))) mmmmaaaalllllllloooocccc((((ssssiiiizzzzeeeeooooffff((((cccchhhhaaaarrrr)))) **** 444488886666))));;;; ////******** AAAA lllloooonnnngggg ssssttttrrrriiiinnnngggg ffffoooolllllllloooowwwwssss!!!! ********////
            sssspppprrrriiiinnnnttttffff((((tttteeeexxxxtttt,,,, """"%%%%ssss"""",,,, """"WWWWhhhheeeennnn hhhheeee iiiissss aaaatttt aaaa ccccoooonnnnvvvveeeennnniiiieeeennnncccceeee ssssttttoooorrrreeee aaaannnndddd tttthhhheeee bbbbiiiillllllll ccccoooommmmeeeessss ttttoooo ssssoooommmmeeee aaaammmmoooouuuunnnntttt lllliiiikkkkeeee 77776666 cccceeeennnnttttssss,,,, MMMMaaaayyyynnnnaaaarrrrdddd iiiissss aaaawwwwaaaarrrreeee tttthhhhaaaatttt tttthhhheeeerrrreeee iiiissss ssssoooommmmeeeetttthhhhiiiinnnngggg hhhheeee ****sssshhhhoooouuuulllldddd**** ddddoooo,,,, ssssoooommmmeeeetttthhhhiiiinnnngggg tttthhhhaaaatttt wwwwiiiillllllll eeeennnnaaaabbbblllleeee hhhhiiiimmmm ttttoooo ggggeeeetttt bbbbaaaacccckkkk aaaa qqqquuuuaaaarrrrtttteeeerrrr,,,, bbbbuuuutttt hhhheeee hhhhaaaassss nnnnoooo iiiiddddeeeeaaaa ****wwwwhhhhaaaatttt****....  HHHHeeee ffffuuuummmmbbbblllleeeessss tttthhhhrrrroooouuuugggghhhh hhhhiiiissss rrrreeeedddd ssssqqqquuuueeeeeeeezzzzeeeeyyyy cccchhhhaaaannnnggggeeeeppppuuuurrrrsssseeee aaaannnndddd ggggiiiivvvveeeessss tttthhhheeee bbbbooooyyyy tttthhhhrrrreeeeeeee eeeexxxxttttrrrraaaa ppppeeeennnnnnnniiiieeeessss wwwwiiiitttthhhh hhhhiiiissss ddddoooollllllllaaaarrrr,,,, hhhhooooppppiiiinnnngggg tttthhhhaaaatttt hhhheeee mmmmiiiigggghhhhtttt lllluuuucccckkkk iiiinnnnttttoooo tttthhhheeee ccccoooorrrrrrrreeeecccctttt aaaammmmoooouuuunnnntttt....  TTTThhhheeee bbbbooooyyyy ggggiiiivvvveeeessss hhhhiiiimmmm bbbbaaaacccckkkk ttttwwwwoooo ooooffff hhhhiiiissss oooowwwwnnnn ppppeeeennnnnnnniiiieeeessss aaaannnndddd tttthhhheeeennnn tttthhhheeee bbbbiiiigggg sssshhhhiiiinnnnyyyy qqqquuuuaaaarrrrtttteeeerrrr tttthhhhaaaatttt iiiissss hhhhiiiissss pppprrrriiiizzzzeeee.... ----RRRRIIIICCCCHHHHHHHH""""))));;;;

            iiiiffff ((((ppppeeeerrrrllll____mmmmaaaattttcccchhhh((((tttteeeexxxxtttt,,,, """"mmmm////qqqquuuuaaaarrrrtttteeeerrrr////"""")))))))) ////******** DDDDooooeeeessss tttteeeexxxxtttt ccccoooonnnnttttaaaaiiiinnnn ''''qqqquuuuaaaarrrrtttteeeerrrr''''???? ********////
              pppprrrriiiinnnnttttffff((((""""ppppeeeerrrrllll____mmmmaaaattttcccchhhh:::: TTTTeeeexxxxtttt ccccoooonnnnttttaaaaiiiinnnnssss tttthhhheeee wwwwoooorrrrdddd ''''qqqquuuuaaaarrrrtttteeeerrrr''''....\\\\nnnn\\\\nnnn""""))));;;;
            eeeellllsssseeee
              pppprrrriiiinnnnttttffff((((""""ppppeeeerrrrllll____mmmmaaaattttcccchhhh:::: TTTTeeeexxxxtttt ddddooooeeeessssnnnn''''tttt ccccoooonnnnttttaaaaiiiinnnn tttthhhheeee wwwwoooorrrrdddd ''''qqqquuuuaaaarrrrtttteeeerrrr''''....\\\\nnnn\\\\nnnn""""))));;;;

            iiiiffff ((((ppppeeeerrrrllll____mmmmaaaattttcccchhhh((((tttteeeexxxxtttt,,,, """"mmmm////eeeeiiiigggghhhhtttthhhh////"""")))))))) ////******** DDDDooooeeeessss tttteeeexxxxtttt ccccoooonnnnttttaaaaiiiinnnn ''''eeeeiiiigggghhhhtttthhhh''''???? ********////
              pppprrrriiiinnnnttttffff((((""""ppppeeeerrrrllll____mmmmaaaattttcccchhhh:::: TTTTeeeexxxxtttt ccccoooonnnnttttaaaaiiiinnnnssss tttthhhheeee wwwwoooorrrrdddd ''''eeeeiiiigggghhhhtttthhhh''''....\\\\nnnn\\\\nnnn""""))));;;;
            eeeellllsssseeee
              pppprrrriiiinnnnttttffff((((""""ppppeeeerrrrllll____mmmmaaaattttcccchhhh:::: TTTTeeeexxxxtttt ddddooooeeeessssnnnn''''tttt ccccoooonnnnttttaaaaiiiinnnn tttthhhheeee wwwwoooorrrrdddd ''''eeeeiiiigggghhhhtttthhhh''''....\\\\nnnn\\\\nnnn""""))));;;;

                                              ////******** MMMMaaaattttcccchhhh aaaallllllll ooooccccccccuuuurrrrrrrreeeennnncccceeeessss ooooffff ////wwwwiiii........//// ********////



30/Jan/96                perl 5.002 with                        9





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


            nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss ==== ppppeeeerrrrllll____mmmmaaaattttcccchhhheeeessss((((tttteeeexxxxtttt,,,, """"mmmm////((((wwwwiiii........))))////gggg"""",,,, &&&&mmmmaaaattttcccchhhheeeessss))));;;;

            pppprrrriiiinnnnttttffff((((""""ppppeeeerrrrllll____mmmmaaaattttcccchhhheeeessss:::: mmmm////((((wwwwiiii........))))////gggg ffffoooouuuunnnndddd %%%%dddd mmmmaaaattttcccchhhheeeessss............\\\\nnnn"""",,,, nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss))));;;;
            ffffoooorrrr ((((iiii ==== 0000;;;; iiii <<<< nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss;;;; iiii++++++++))))
              pppprrrriiiinnnnttttffff((((""""mmmmaaaattttcccchhhh:::: %%%%ssss\\\\nnnn"""",,,, mmmmaaaattttcccchhhheeeessss[[[[iiii]]]]))));;;;
            pppprrrriiiinnnnttttffff((((""""\\\\nnnn""""))));;;;
            ffffoooorrrr ((((iiii ==== 0000;;;; iiii <<<< nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss;;;; iiii++++++++)))) {{{{
              ffffrrrreeeeeeee((((mmmmaaaattttcccchhhheeeessss[[[[iiii]]]]))));;;;
            }}}}
            ffffrrrreeeeeeee((((mmmmaaaattttcccchhhheeeessss))));;;;

                                              ////******** RRRReeeemmmmoooovvvveeee aaaallllllll vvvvoooowwwweeeellllssss ffffrrrroooommmm tttteeeexxxxtttt ********////
            nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss ==== ppppeeeerrrrllll____ssssuuuubbbbssssttttiiiittttuuuutttteeee((((&&&&tttteeeexxxxtttt,,,, """"ssss////[[[[aaaaeeeeiiiioooouuuu]]]]////////ggggiiii""""))));;;;
            iiiiffff ((((nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss)))) {{{{
              pppprrrriiiinnnnttttffff((((""""ppppeeeerrrrllll____ssssuuuubbbbssssttttiiiittttuuuutttteeee:::: ssss////[[[[aaaaeeeeiiiioooouuuu]]]]////////ggggiiii............%%%%dddd ssssuuuubbbbssssttttiiiittttuuuuttttiiiioooonnnnssss mmmmaaaaddddeeee....\\\\nnnn"""",,,,
               nnnnuuuummmm____mmmmaaaattttcccchhhheeeessss))));;;;
              pppprrrriiiinnnnttttffff((((""""NNNNoooowwww tttteeeexxxxtttt iiiissss:::: %%%%ssss\\\\nnnn\\\\nnnn"""",,,, tttteeeexxxxtttt))));;;;
            }}}}

                                              ////******** AAAAtttttttteeeemmmmpppptttt aaaa ssssuuuubbbbssssttttiiiittttuuuuttttiiiioooonnnn
            iiiiffff ((((!!!!ppppeeeerrrrllll____ssssuuuubbbbssssttttiiiittttuuuutttteeee((((&&&&tttteeeexxxxtttt,,,, """"ssss////PPPPeeeerrrrllll////CCCC////"""")))))))) {{{{
              pppprrrriiiinnnnttttffff((((""""ppppeeeerrrrllll____ssssuuuubbbbssssttttiiiittttuuuutttteeee:::: ssss////PPPPeeeerrrrllll////CCCC............NNNNoooo ssssuuuubbbbssssttttiiiittttuuuuttttiiiioooonnnn mmmmaaaaddddeeee....\\\\nnnn\\\\nnnn""""))));;;;
            }}}}

            ffffrrrreeeeeeee((((tttteeeexxxxtttt))));;;;

            ppppeeeerrrrllll____ddddeeeessssttttrrrruuuucccctttt((((mmmmyyyy____ppppeeeerrrrllll))));;;;
            ppppeeeerrrrllll____ffffrrrreeeeeeee((((mmmmyyyy____ppppeeeerrrrllll))));;;;
          }}}}

       which produces the output

          ppppeeeerrrrllll____mmmmaaaattttcccchhhh:::: TTTTeeeexxxxtttt ccccoooonnnnttttaaaaiiiinnnnssss tttthhhheeee wwwwoooorrrrdddd ''''qqqquuuuaaaarrrrtttteeeerrrr''''....

          ppppeeeerrrrllll____mmmmaaaattttcccchhhh:::: TTTTeeeexxxxtttt ddddooooeeeessssnnnn''''tttt ccccoooonnnnttttaaaaiiiinnnn tttthhhheeee wwwwoooorrrrdddd ''''eeeeiiiigggghhhhtttthhhh''''....

          ppppeeeerrrrllll____mmmmaaaattttcccchhhheeeessss:::: mmmm////((((wwwwiiii........))))////gggg ffffoooouuuunnnndddd 2222 mmmmaaaattttcccchhhheeeessss............
          mmmmaaaattttcccchhhh:::: wwwwiiiillllllll
          mmmmaaaattttcccchhhh:::: wwwwiiiitttthhhh

          ppppeeeerrrrllll____ssssuuuubbbbssssttttiiiittttuuuutttteeee:::: ssss////[[[[aaaaeeeeiiiioooouuuu]]]]////////ggggiiii............111133339999 ssssuuuubbbbssssttttiiiittttuuuuttttiiiioooonnnnssss mmmmaaaaddddeeee....
          NNNNoooowwww tttteeeexxxxtttt iiiissss:::: WWWWhhhhnnnn hhhh ssss tttt  ccccnnnnvvvvnnnnnnnncccc ssssttttrrrr nnnndddd tttthhhh bbbbllllllll ccccmmmmssss tttt ssssmmmm mmmmnnnntttt llllkkkk 77776666 ccccnnnnttttssss,,,, MMMMyyyynnnnrrrrdddd ssss wwwwrrrr tttthhhhtttt tttthhhhrrrr ssss ssssmmmmtttthhhhnnnngggg hhhh ****sssshhhhlllldddd**** dddd,,,, ssssmmmmtttthhhhnnnngggg tttthhhhtttt wwwwllllllll nnnnbbbbllll hhhhmmmm tttt ggggtttt bbbbcccckkkk  qqqqrrrrttttrrrr,,,, bbbbtttt hhhh hhhhssss nnnn dddd ****wwwwhhhhtttt****....  HHHH ffffmmmmbbbbllllssss tttthhhhrrrrgggghhhh hhhhssss rrrrdddd ssssqqqqzzzzyyyy cccchhhhnnnnggggpppprrrrssss nnnndddd ggggvvvvssss tttthhhh bbbbyyyy tttthhhhrrrr xxxxttttrrrr ppppnnnnnnnnssss wwwwtttthhhh hhhhssss ddddllllllllrrrr,,,, hhhhppppnnnngggg tttthhhhtttt hhhh mmmmgggghhhhtttt llllcccckkkk nnnntttt tttthhhh ccccrrrrrrrrcccctttt mmmmnnnntttt....  TTTThhhh bbbbyyyy ggggvvvvssss hhhhmmmm bbbbcccckkkk ttttwwww ffff hhhhssss wwwwnnnn ppppnnnnnnnnssss nnnndddd tttthhhhnnnn tttthhhh bbbbgggg sssshhhhnnnnyyyy qqqqrrrrttttrrrr tttthhhhtttt ssss hhhhssss pppprrrrzzzz.... ----RRRRCCCCHHHHHHHH

          ppppeeeerrrrllll____ssssuuuubbbbssssttttiiiittttuuuutttteeee:::: ssss////PPPPeeeerrrrllll////CCCC............NNNNoooo ssssuuuubbbbssssttttiiiittttuuuuttttiiiioooonnnn mmmmaaaaddddeeee....

       ====hhhheeeeaaaadddd2222 FFFFiiiiddddddddlllliiiinnnngggg wwwwiiiitttthhhh tttthhhheeee PPPPeeeerrrrllll ssssttttaaaacccckkkk ffffrrrroooommmm yyyyoooouuuurrrr CCCC pppprrrrooooggggrrrraaaammmm

       When trying to explain stacks, most computer science
       textbooks mumble something about spring-loaded columns of
       cafeteria plates: the last thing you pushed on the stack
       is the first thing you pop off.  That'll do for our
       purposes: your C program will push some arguments onto
       "the Perl stack", shut its eyes while some magic happens,
       and then pop the results--the return value of your Perl



30/Jan/96                perl 5.002 with                       10





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


       subroutine--off the stack.

       First you'll need to know how to convert between C types
       and Perl types, with _n_e_w_S_V_i_v_(_) and _s_v___s_e_t_n_v_(_) and _n_e_w_A_V_(_)
       and all their friends.  They're described in the _p_e_r_l_g_u_t_s
       manpage.

       Then you'll need to know how to manipulate the Perl stack.
       That's described in the _p_e_r_l_c_a_l_l manpage.

       Once you've understood those, embedding Perl in C is easy.

       Since C has no built-in function for integer
       exponentiation, let's make Perl's ** operator available to
       it (this is less useful than it sounds, since Perl
       implements ** with C's _p_o_w_(_) function).  First I'll create
       a stub exponentiation function in _p_o_w_e_r_._p_l:

           ssssuuuubbbb eeeexxxxppppoooo {{{{
               mmmmyyyy (((($$$$aaaa,,,, $$$$bbbb)))) ==== @@@@____;;;;
               rrrreeeettttuuuurrrrnnnn $$$$aaaa ******** $$$$bbbb;;;;
           }}}}

       Now I'll create a C program, _p_o_w_e_r_._c, with a function
       _P_e_r_l_P_o_w_e_r_(_) that contains all the perlguts necessary to
       push the two arguments into _e_x_p_o_(_) and to pop the return
       value out.  Take a deep breath...






























30/Jan/96                perl 5.002 with                       11





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


           ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
           ####iiiinnnncccclllluuuuddddeeee <<<<EEEEXXXXTTTTEEEERRRRNNNN....hhhh>>>>
           ####iiiinnnncccclllluuuuddddeeee <<<<ppppeeeerrrrllll....hhhh>>>>

           ssssttttaaaattttiiiicccc PPPPeeeerrrrllllIIIInnnntttteeeerrrrpppprrrreeeetttteeeerrrr ****mmmmyyyy____ppppeeeerrrrllll;;;;

           ssssttttaaaattttiiiicccc vvvvooooiiiidddd
           PPPPeeeerrrrllllPPPPoooowwwweeeerrrr((((iiiinnnntttt aaaa,,,, iiiinnnntttt bbbb))))
           {{{{
             ddddSSSSPPPP;;;;                            ////**** iiiinnnniiiittttiiiiaaaalllliiiizzzzeeee ssssttttaaaacccckkkk ppppooooiiiinnnntttteeeerrrr      ****////
             EEEENNNNTTTTEEEERRRR;;;;                          ////**** eeeevvvveeeerrrryyyytttthhhhiiiinnnngggg ccccrrrreeeeaaaatttteeeedddd aaaafffftttteeeerrrr hhhheeeerrrreeee ****////
             SSSSAAAAVVVVEEEETTTTMMMMPPPPSSSS;;;;                       ////**** ............iiiissss aaaa tttteeeemmmmppppoooorrrraaaarrrryyyy vvvvaaaarrrriiiiaaaabbbblllleeee....   ****////
             PPPPUUUUSSSSHHHHMMMMAAAARRRRKKKK((((sssspppp))));;;;                   ////**** rrrreeeemmmmeeeemmmmbbbbeeeerrrr tttthhhheeee ssssttttaaaacccckkkk ppppooooiiiinnnntttteeeerrrr    ****////
             XXXXPPPPUUUUSSSSHHHHssss((((ssssvvvv____2222mmmmoooorrrrttttaaaallll((((nnnneeeewwwwSSSSVVVViiiivvvv((((aaaa))))))))))));;;; ////**** ppppuuuusssshhhh tttthhhheeee bbbbaaaasssseeee oooonnnnttttoooo tttthhhheeee ssssttttaaaacccckkkk  ****////
             XXXXPPPPUUUUSSSSHHHHssss((((ssssvvvv____2222mmmmoooorrrrttttaaaallll((((nnnneeeewwwwSSSSVVVViiiivvvv((((bbbb))))))))))));;;; ////**** ppppuuuusssshhhh tttthhhheeee eeeexxxxppppoooonnnneeeennnntttt oooonnnnttttoooo ssssttttaaaacccckkkk  ****////
             PPPPUUUUTTTTBBBBAAAACCCCKKKK;;;;                      ////**** mmmmaaaakkkkeeee llllooooccccaaaallll ssssttttaaaacccckkkk ppppooooiiiinnnntttteeeerrrr gggglllloooobbbbaaaallll ****////
             ppppeeeerrrrllll____ccccaaaallllllll____ppppvvvv((((""""eeeexxxxppppoooo"""",,,, GGGG____SSSSCCCCAAAALLLLAAAARRRR))));;;; ////**** ccccaaaallllllll tttthhhheeee ffffuuuunnnnccccttttiiiioooonnnn             ****////
             SSSSPPPPAAAAGGGGAAAAIIIINNNN;;;;                        ////**** rrrreeeeffffrrrreeeesssshhhh ssssttttaaaacccckkkk ppppooooiiiinnnntttteeeerrrr         ****////
                                           ////**** ppppoooopppp tttthhhheeee rrrreeeettttuuuurrrrnnnn vvvvaaaalllluuuueeee ffffrrrroooommmm ssssttttaaaacccckkkk ****////
             pppprrrriiiinnnnttttffff ((((""""%%%%dddd ttttoooo tttthhhheeee %%%%ddddtttthhhh ppppoooowwwweeeerrrr iiiissss %%%%dddd....\\\\nnnn"""",,,, aaaa,,,, bbbb,,,, PPPPOOOOPPPPiiii))));;;;
             PPPPUUUUTTTTBBBBAAAACCCCKKKK;;;;
             FFFFRRRREEEEEEEETTTTMMMMPPPPSSSS;;;;                       ////**** ffffrrrreeeeeeee tttthhhhaaaatttt rrrreeeettttuuuurrrrnnnn vvvvaaaalllluuuueeee        ****////
             LLLLEEEEAAAAVVVVEEEE;;;;                       ////**** ............aaaannnndddd tttthhhheeee XXXXPPPPUUUUSSSSHHHHeeeedddd """"mmmmoooorrrrttttaaaallll"""" aaaarrrrggggssss....****////
           }}}}

           iiiinnnntttt mmmmaaaaiiiinnnn ((((iiiinnnntttt aaaarrrrggggcccc,,,, cccchhhhaaaarrrr ********aaaarrrrggggvvvv,,,, cccchhhhaaaarrrr ********eeeennnnvvvv))))
           {{{{
             cccchhhhaaaarrrr ****mmmmyyyy____aaaarrrrggggvvvv[[[[2222]]]];;;;

             mmmmyyyy____ppppeeeerrrrllll ==== ppppeeeerrrrllll____aaaalllllllloooocccc(((())));;;;
             ppppeeeerrrrllll____ccccoooonnnnssssttttrrrruuuucccctttt(((( mmmmyyyy____ppppeeeerrrrllll ))));;;;

             mmmmyyyy____aaaarrrrggggvvvv[[[[1111]]]] ==== ((((cccchhhhaaaarrrr ****)))) mmmmaaaalllllllloooocccc((((11110000))));;;;
             sssspppprrrriiiinnnnttttffff((((mmmmyyyy____aaaarrrrggggvvvv[[[[1111]]]],,,, """"ppppoooowwwweeeerrrr....ppppllll""""))));;;;

             ppppeeeerrrrllll____ppppaaaarrrrsssseeee((((mmmmyyyy____ppppeeeerrrrllll,,,, NNNNUUUULLLLLLLL,,,, aaaarrrrggggcccc,,,, mmmmyyyy____aaaarrrrggggvvvv,,,, eeeennnnvvvv))));;;;

             PPPPeeeerrrrllllPPPPoooowwwweeeerrrr((((3333,,,, 4444))));;;;                      ////************ CCCCoooommmmppppuuuutttteeee 3333 ******** 4444 ************////

             ppppeeeerrrrllll____ddddeeeessssttttrrrruuuucccctttt((((mmmmyyyy____ppppeeeerrrrllll))));;;;
             ppppeeeerrrrllll____ffffrrrreeeeeeee((((mmmmyyyy____ppppeeeerrrrllll))));;;;
           }}}}


       Compile and run:

           %%%% cccccccc ----oooo ppppoooowwwweeeerrrr ppppoooowwwweeeerrrr....cccc ----LLLL////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////aaaallllpppphhhhaaaa----ddddeeeecccc____oooossssffff////CCCCOOOORRRREEEE
           ----IIII////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ppppeeeerrrrllll5555////aaaallllpppphhhhaaaa----ddddeeeecccc____oooossssffff////CCCCOOOORRRREEEE ----llllppppeeeerrrrllll ----llllmmmm

           %%%% ppppoooowwwweeeerrrr
           3333 ttttoooo tttthhhheeee 4444tttthhhh ppppoooowwwweeeerrrr iiiissss 88881111....






30/Jan/96                perl 5.002 with                       12





PERLEMBED(1)   User Contributed Perl Documentation   PERLEMBED(1)


MMMMOOOORRRRAAAALLLL
       You can sometimes _w_r_i_t_e _f_a_s_t_e_r _c_o_d_e in C, but you can
       always _w_r_i_t_e _c_o_d_e _f_a_s_t_e_r in Perl.  Since you can use each
       from the other, combine them as you wish.

AAAAUUUUTTTTHHHHOOOORRRR
       Jon Orwant _<_o_r_w_a_n_t_@_m_e_d_i_a_._m_i_t_._e_d_u_>, with contributions from
       Tim Bunce, Tom Christiansen, Dov Grobgeld, and Ilya
       Zakharevich.

       December 18, 1995

       Some of this material is excerpted from my book: _P_e_r_l _5
       _I_n_t_e_r_a_c_t_i_v_e, Waite Group Press, 1996 (ISBN 1-57169-064-6)
       and appears courtesy of Waite Group Press.










































30/Jan/96                perl 5.002 with                       13